<HTML><HEAD><TITLE>store_get(+StoreHandle, ++Key, -Value)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Non-logical Variables, Arrays, Bags, Shelves and Stores</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>store_get(+StoreHandle, ++Key, -Value)</H1>
Look up an entry in a store object
<DL>
<DT><EM>StoreHandle</EM></DT>
<DD>A store handle or store name
</DD>
<DT><EM>Key</EM></DT>
<DD>A ground term
</DD>
<DT><EM>Value</EM></DT>
<DD>A variable or arbitrary term
</DD>
</DL>
<H2>Description</H2>
	This looks up an entry under a given key in a given store object.
	If an entry for this key exists, the corresponding value is returned,
	otherwise the predicate fails.
<P>
	The key can be arbitrarily complex, but must be a ground term.
	The value can be an arbitrary term, and may contain uninstantiated
	variables. Note that values are copied when being stored or
	retrieved, therefore a retrieved nonground value will contain
	fresh variables rather than the original ones (this is similar
	to the behaviour of bags, shelves and global variables).
<P>
	The complexity of the retrieval operation is linear in both the size
	of the key and the value, since the value is being copied and the key
	needs to be compared. For indexing purposes, a hash value is computed
	from the key, and the full depth of the key is taken into account.
<P>
	Note: If StoreHandle is not a handle, then it must be an atom or a
	compound term, and the store is identified by this term's toplevel
	functor together with the context module.
<P>
    
<H3>Modes and Determinism</H3><UL>
<LI>store_get(+, ++, -) is semidet
</UL>
<H3>Modules</H3>
This predicate is sensitive to its module context (tool predicate, see @/2).
<H3>Fail Conditions</H3>
The store does not contain an entry for Key
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>StoreHandle is uninstantiated
<DT><EM>(4) instantiation fault </EM>
<DD>Key is not ground
<DT><EM>(5) type error </EM>
<DD>StoreHandle is neither atom nor compound term nor store handle
<DT><EM>(45) record does not exist </EM>
<DD>StoreHandle is not the name of a store
</DL>
<H2>Examples</H2>
<PRE>

    ?- store_create(Handle),
       store_set(Handle, tom, 12345),
       store_set(Handle, name(dick,tracy), phone(42376,home)),
       store_set(Handle, numbers:prime, [2,3,5,7|_More]),
       store_get(Handle, tom, Value1),
       store_get(Handle, name(dick,tracy), Value2),
       store_get(Handle, numbers:prime, Value3).

    Handle = 'STORE'(16'001b3c50)
    Value1 = 12345
    Value2 = phone(42376, home)
    Value3 = [2, 3, 5, 7|_More]
    Yes (0.00s cpu)


    ?- store_create(Handle),
       store_set(Handle, tom, 12345),
       store_get(Handle, harry, Value).

    No (0.00s cpu)
    </PRE>
<H2>See Also</H2>
<A HREF="../../kernel/storage/store-1.html">store / 1</A>, <A HREF="../../kernel/modules/local-1.html">local / 1</A>, <A HREF="../../kernel/storage/store_erase-1.html">store_erase / 1</A>, <A HREF="../../kernel/storage/store_set-3.html">store_set / 3</A>, <A HREF="../../kernel/storage/store_delete-2.html">store_delete / 2</A>, <A HREF="../../kernel/storage/store_contains-2.html">store_contains / 2</A>, <A HREF="../../kernel/storage/stored_keys-2.html">stored_keys / 2</A>, <A HREF="../../kernel/storage/stored_keys_and_values-2.html">stored_keys_and_values / 2</A>, <A HREF="../../kernel/storage/store_create-1.html">store_create / 1</A>, <A HREF="../../kernel/storage/store_count-2.html">store_count / 2</A>, <A HREF="../../kernel/storage/store_inc-2.html">store_inc / 2</A>
</BODY></HTML>
